Preview all models that will be run

Returns a data frame describing every model run that fit_models would execute, without actually fitting any models. Useful for verifying model specifications and confirming the set of runs before committing to a potentially long parallel execution.

Usage

preview_fit(models, data, defs, weight_var = NULL, weighted_only = FALSE)

Arguments

models

A named list of model_spec objects, one per model to run. Names become the keys in the returned results list.

data

A data frame, or a named list of data frames. When a list is provided, every model is run once per dataset.

defs

A named list of definition lists. Each element must contain:

dv

Character. The dependent variable name.

fun

Function (or named list of functions) with signature f(formula, data, weights), or a character string naming a function (e.g. "lm" or "fixest::feols"). A string is wrapped into function(f, d, w, ...) <fun>(f, data = d, weights = w, ...), The formula is passed as the first argument, whatever that argument is called. Arguments set with set_args are passed as further named arguments, so a function fitting such a model needs ... or arguments of those names.

and may optionally contain:

extra_terms

Character vector of terms appended to every model's main terms (but not to its parts; see set_parts) for this DV only.

additional_models

Named list of model_spec objects added to the model set for this DV only.

model_mods

Named list of functions of the form function(model_spec) -> model_spec. Each entry modifies the named base model for this DV only, leaving other DVs unchanged.

weight_var

Character. Name of a column in data to use as regression weights. When supplied, each model is run twice: once unweighted and once weighted. Default NULL (no weights).

weighted_only

Logical. When TRUE and weight_var is supplied, only the weighted variants are run. Default FALSE.

Value

A tibble with one row per model run and columns:

def

The name of the definition in defs that produced this run (i.e. the key used to index the outer results list returned by fit_models).

dv

Dependent variable name.

model

Model name (from models).

dataset

Dataset name. Only present when data is a named list of data frames; omitted for a single data frame.

weighted

Logical; TRUE for weighted runs, FALSE for unweighted runs. Only present when weight_var is supplied and weighted_only = FALSE (i.e. when both variants appear); omitted otherwise.

key

The name the corresponding result will have in the inner list for this definition, formed by joining model, dataset, and weight suffix with ".".

formula

Character representation of the formula that would be passed to the regression function.

args

Extra arguments the model's spec carries (see set_args), as a one-line summary. Only present when at least one run has them; NA for runs without arguments.

See also

fit_models

Examples

base_m <- model_spec(cyl, disp)
models <- list(base = base_m, ext = base_m |> add_terms(hp))
defs <- list(mpg = list(dv = "mpg", fun = "lm"))
preview_fit(models, mtcars, defs)
#> # A tibble: 2 × 5
#>   def   dv    model key   formula              
#>   <chr> <chr> <chr> <chr> <chr>                
#> 1 mpg   mpg   base  base  mpg ~ cyl + disp     
#> 2 mpg   mpg   ext   ext   mpg ~ cyl + disp + hp